User's Choice Windows CD/User's Choice Windows CD (CMS Software)(1993).iso/windows4/stdm10.zip/README.TXT

Text File | 1992-11-28 | 19KB | 592 lines

            Stdemo Player 1.0
        Copyright (c) 1992 Mik Kvitchko

-----------------------------
| Mikhail Kvitchko          |
| 289-D Crowells Road,      |
| Highland Park, NJ 08904   |
| USA                       |
-----------------------------

This package consists of the following files:

README.TXT    - This File
STHOOK.DLL    - Windows Input Messages Interception DLL
STDEMO.EXE    - Stdemo Player Program
SCRIPT.TXT    - Stdemo Player Example Script

What is this?
=============

Stdemo Player is an application that you can use to create demos,
tutorials or manually prepare scripts to "play" them into any
Windows application. It allows you to write a script, which will
start one or several Windows application, perform a series of
keystrokes or mouse actions aimed to demonstrate the application or
to perform some pre-defined sequence of actions. While your script
is being "played", you can disable completely keyboard and mouse,
so that user will not be able to interfere with the running demo
and to cause a conflict. At certain points of you script you may
interrupt it in order to interact with user. These interactions
allow:

-    to show the "text" box with some explanatory text before
    script will continue ( this is the main idea of how demos
    and tutorials are to be designed);

-    to show the "menu" box where user can select one of several
    choices, and therefore control the script's execution;

-    to show the "input" box, where user can answer questions and
    enter some text, which later can be used in script.

There are many varieties of these boxes in order to make your demo
flexible, and they can be forced to be shown in some convenient
places on the screen. Moreover, user can move them across the
screen to be able to see different parts of the covered windows.

Even if you are not interested in preparing demos, you may find
Stdemo Player useful. For example, you can replace your complete
Startup Group to the single Stdemo Player script which will launch
all your "startup" applications, and even perform some initial
actions for every of them: set up default options, load files, etc.

How to play the script?
======================

When you run stdemo.exe without parameters, it looks for the file
"script.txt" in the current working directory, and if it is there -
"plays" it.

Also you may pass the name of the script as a parameter to
stdemo.exe. This name may include the full path.


How to write a script?
======================

Script is a plain ASCII text file. It may include:

-    keystrokes;
-    commands;
-    interaction breaks;
-    comments.

Every keystroke, command or interaction break is a unit. Stdemo
Player reads units from the script one by one and executes them.
After one unit is executed, Stdemo Player waits for some time
(time-out tick, which can be set or changed at any point in the
script) and then executes the next unit. Time-out doesn't affect
the interaction breaks (which are "text", "menu" and "input" dialog
boxes). Once one of this boxes is shown - only user may continue or
stop script execution, selecting "Continue" or "Stop" button on the
box. Comments are ignored, as you may expect, and cause no time-out
delays.

1. Keystrokes.
--------------

Any text in the script which is not a command, interaction break or
comment is a set of keystrokes, i.e. every symbol of the text
causes a keystroke to be sent into the current window application
(see  below).
There are also several special symbols which allow to simulate
different keyboard keys.

Any keystroke can be preceded by one or more special symbols
("@" - Alt, "#" - Shift or/and "%" - Control) as you see in the
following example:

@A    Alt-A
#A    Shift-A
%A    Ctrl-A
#%A    Shift-Ctrl-A

There are also many special keys which are coded by "escaping" them
with the "]". They are follows:

]|    Down
]^    Up
]<    Left
]>    Right
]~    Tab
]!    Return
]-    PgUp
]+    PgDn
]\    Backspace
]Z    Esc
]I    Ins
]D    Del
]H    Home
]E    End
]0    F10
]1    F1
...........
]9    F9
]]    ]
]@    @
]%    %
]#    #
]:    :
]$    $

This is not a full set of the keyboard keys, as you may note - but
it covers most of usable ones (I hope).

2. Commands.
------------

All commands start from the colon sign ":". Some of the commands
must be coded as a separate line in a script, others can be mixed
with the keystrokes. The rule of a thumb is: if a command has fixed
format or ends with the special separator - it can be placed
anywhere, otherwise it has to be coded as a separate line of the
script. The general format of a command is:
    :<code><parameters>
<code> is a single letter or some other symbol;
<parameters> may vary; one parameter can be a letter, text or
number; parameters follow the code without blank, and in some cases
are separated one from another by the special separator "|".

The commands are:

:=x            set time-out tick to x milliseconds.
            Default time-out is 1 millisecond.
    Example:
    :=1000    set time-out tick to 1 sec.

:T            skip 1 time-out tick.
    Example:
    abc:T:T:Tefg    enter "abc", then wait for three
            current time-out ticks, then enter
            "efg".

:Dtext            change current directory to "text".
    Example:
    :Dc:\windows\system

:(app-name parm|x    launch the application;
            program name must include extension (for the
            security reason) and may include the full path;
            parameters to the program can be passed, if
            needed (not required);
            flag x may be coded as one digit 0..2 after the
            separator and affects the size of the
            application window: 0 (default), 1(maximize),
            2(minimize).
    Examples:
    :(notepad.exe
    :(c:\windows\write.exe demo.wri
    :(notepad.exe c:\stdemo\readme.txt|2

:)            kill the last application in stack (if exists).

    Note:    Stdemo Player allows to start several applications.
        It keeps track of the applications being started in
        the internal stack ( max. 10 entries). When you start
        a new application, the following keystrokes will be
        sent into the new application window, as it will
        get focus after the launch. You must issue ":)" -
        kill last application - command, even when you finish
        the application using it's menu commands - so that
        Stdemo Player could handle the stack of current
        applications properly.
        There is no command ( so far ) to switch focus from
        one application to another. Though you can do this by
        simulating mouse clicking in the proper window. Just
        make sure that you close applications in the reverse
        order as you started them, and issue correspondent
        ":)" commands in the same reverse order.

:Iab            enable/disable Windows input;
            parameter "a" must be coded as one digit:
            0 - disable input, 1 - enable input;
            parameter "b" is also 1 digit:
            0 - temporarily, 1 - permanently.
    Example:
    :I10    enable input until the next interaction break.

    Note:    When stdemo starts, it disables Windows input
        (keyboard and mouse buttons) in order to prevent
        user's intervention into the actions being played.
        When one of the interaction breaks occurs, the input
        is partially restored to allow user interaction
        inside the dialog box only. When script continues,
        the state is restored as it was before the break.
        "Temporarily change the state of Windows input" means
        "until the next interaction break occurs". Permanent
        change affects all subsequent script play and can be
        changed with the next ":I" command only.

:Cab            show/hide Windows cursor;
            parameter "a" must be coded as one digit:
            0 - hide cursor, 1 - show cursor;
            parameter "b" is also 1 digit:
            0 - temporarily, 1 - permanently.
    Example:
    :C11    show Windows cursor until further ":C" command.

    Note:    When stdemo starts, it hides Windows cursor.
        When one of the interaction breaks occurs, the cursor
        is restored to allow user interaction inside the
        dialog box only. When script continues, the state is
        restored as it was before the break.
        "Temporarily change the visibility of cursor" means
        "until the next interaction break occurs". Permanent
        change affects all subsequent script play and can be
        changed with the next ":C" command only.

:Ltext            assign the label "text" to the current point in
            the script.
:Gtext            goto label "text".

    Note:     these two commands apparently do not require
        explanation. Just note that so far there is no
        conditional "goto" command. So you can use ":G"
        command to code the loop, or to skip part of the
        script during debugging. Labels are required when
        you program a "menu" interaction break (see below).

:$ntext        set variable n to "text" (n=0..9).
    Example:
    :$1Hello
    :$2, how are you?

    Note:    variables can be used among the keystrokes, i.e.,
        using previous example, script "$1 Joe$2" will
        play "Hello Joe, how are you?". Variables are
        extensively used in the "input" interaction breaks
        (see below).


The following commands are to be used when you want some mouse
actions to be played from your script. It is not always possible to
get a reliable results with the mouse actions, assuming that your
script can be played with different display drivers in different
Windows modes and display resolutions. In order to cope with this,
you must use "virtual" coordinates, i.e. before using any command
which has coordinates as a parameter, you have to set "virtual
screen/window size" and then all following coordinates must be
coded according to this size. When your script will be played,
Stdemo Player will determine the real current screen/window size,
and then adjust all your virtual coordinates according to
virtual/real ratio. You have to understand, that it is not a
perfect solution - for example, dialog boxes sizes are not
proportionally changed for different display resolutions, they
depend on the size of the system font rather than on display mode.
But if you code your mouse actions inside the dialog box, based on
the dialog box virtual size - it will work.

:Sx|y            set virtual screen/window size.
    Example:
    :S1024|768
    :S100|50

:Oab            set coordinates origin.
            parameter "a" must be coded as one letter:
            S - screen, A - application main window,
            F - current focus window;
            parameter "b" is also 1 letter:
            C - client area, W - window area.
    Examples:
    :OSW
    :OAC
    :OFW

:Mx|y|n        move mouse cursor to (x,y) in n steps.

    Examples:
    :S200|200
    :OAC
    :C11
    :M100|100|1    set cursor in the center of the client area
            of the main application window.
    :M0|200|100    move cursor in 100 steps to the bottom-left
            corner of the client area.

    Note:    Make sure that your coordinates agree with the
        current modes set in ":S" and ":O" commands.

:Bab            mouse button action.
            parameter "a" must be coded as one letter:
            L - left button, R - right button, M - middle;
            parameter "b" must be coded as 1 digit:
            1 - press, 0 - release, 2 - double-click.

:Kab            set keyboard state for some special keys.
            parameter "a" must be coded as one letter:
            S - Shift key, C - Control key, A - Alt key;
            parameter "b" must be coded as 1 digit:
            1 - down, 0 - up.

    Example:
    :KS1:BL1:BL0:KS0    click the left mouse button when the
                Shift key is down.


3. Interaction breaks.
----------------------

These are various dialog boxes which can be shown at any point of
you script, allowing therefore some interaction with user. There
are three classes of these boxes: "text", "menu" and "input". Each
class contains from 3 to 5 similar boxes, which vary by their size
and by the number of fields in them.
All boxes are coded in the script differently, but the common
pattern is:

<header line>
<one or more body lines>
<end-of-box delimiter line>

3.1 TEXT interaction break.
+++++++++++++++++++++++++++

Every TEXT box has a single text field which fills the dominant
area of the box.

The header line is:
:#sxy
    parameter "s" defines the size and must be a letter:
    S - small, M - medium, L - large, W - wide, N - narrow;
    parameter x defines the position along the x-axis:
    L - left adjusted, C - centered, R - right adjusted;
    parameter y defines the position along the y-axis:
    U - up adjusted, C - centered, D - down adjusted.

The body of this break consists from the text only, which will be
shown in the single text field of the box. Text may be coded as one
or more lines in the script, but it'll be placed continuously in
the box, applying word wrap. There are two special commands which
can be entered into the body of the TEXT box:
.N    causes the following text start from a new line in a box;
.S    causes to skip one line and continue to fill a box with the
    following text.

The delimiter line is:
#

Example:

:#NCC
This is the narrow box, centered on the screen.
.S
This text starts after the empty line.
.N
This text starts from the beginning of the new line.
#

3.2 MENU interaction break.
+++++++++++++++++++++++++++

Every MENU box has a header text field on a top and from 2 to 9
menu item fields ( radio buttons).

The header line is:
:*sxy
    parameter "s" defines the size and must be a letter:
    S - small, M - medium, L - large;
    parameter x defines the position along the x-axis:
    L - left adjusted, C - centered, R - right adjusted;
    parameter y defines the position along the y-axis:
    U - up adjusted, C - centered, D - down adjusted.

The body of this break consists from the text which will fill the
header text field of the menu box, and two or more menu lines.
Text may be coded as one or more lines anywhere in the body; it'll
be placed continuously in the header field, using word wrap if
appropriate. Text line should not start from a digit.
Every menu item line has the following format:

nlabel|item text

"n" is a menu item field number (1..9);
"label" - is a label in the script where control will be passed if
this item will be selected from the menu box.
"item text" is a text to fill the menu item field.

The delimiter line is:
*

Notes:        1. The "small" menu box has 2 menu fields, the
           "medium" - 5 fields, and the large - 9 fields.

        2. If there is no text for the header - the header
           field will not be shown in the box.

        3. If there is no lines for some menu items - the
           correspondent item field will not be shown in the
           box.
Example:

:*MCU
Select one of the three:
1l1|This is the first item
3l2|This is the second item
5l3|This is the third item
*
:Ll1
:#SCC
You've selected the first.
#
:Gcont
:Ll2
:#SCC
You've selected the second.
#
:Gcont
:Ll3
:#SCC
You've selected the third.
#
:Lcont


3.3 INPUT interaction break.
++++++++++++++++++++++++++++

Every INPUT box has a header text field on a top of the box and
from 1 to 9 edit fields. The small box has only one edit field, the
medium has 5, and the large has 9. Every edit field in the medium
and large INPUT boxes has the correspondent description field on a
left of the every edit field.

The header line is:
:%sxy
    parameter "s" defines the size and must be a letter:
    S - small, M - medium, L - large;
    parameter x defines the position along the x-axis:
    L - left adjusted, C - centered, R - right adjusted;
    parameter y defines the position along the y-axis:
    U - up adjusted, C - centered, D - down adjusted.

The body of this break consists from the text which will fill the
header text field of the menu box, and one or more input lines.
Text may be coded as one or more lines anywhere in the body; it'll
be placed continuously in the header field, using word wrap if
appropriate. Text line should not start from a digit.
Every input line has the following format:

nDescription_Text

"n" is a input field number (1..9); the correspondent input field
will be filled with the current value of the variable $n. If the
variable is empty - the field will also be empty.

"Description_Text" is a text to fill the description field for the
"n"-th input field.

The delimiter line is:
%

Notes:        1. The "small" input box has 1 edit field, the
           "medium" - 5 fields, and the large - 9 fields.

        2. If there is no text for the header - the header
           field will not be shown in the box.

        3. If there is no line for some edit field - the
           correspondent edit and description fields will not
           be shown in the box.

        4. After user entered some text in the input field -
           this text will be assigned to the correspondent
           variable ($1..$9).
Example:

:(notepad.exe|1
:$2John
:%MCU
Please correct your name.
2Your first name:
4Your last name:
%
Hello, $2 $4!
:#SRD
Is my greeting correct?
#
:)


4. Comments.
------------

Any line in the script outside the interaction breaks, which starts
from "//" is being treated as a comment.


Future.
=======

I'm sure you noticed that the program can be further extended
( for example, auto recorder would not do any harm ). Please,
share your ideas with me, if you are interested.

Acknowledgments.
================

1. Thanks to CompuServe and all participants of the WinSdk
   forum - you were my teachers, when I started programming
   Windows half a year ago.

2. Thanks to Brent Rector, whose book "Developing Windows 3
   Applications" (and once he personally) helped me along
   my way of learning Windows.

3. Thanks to my employers and friends Ken Winston and Michael
   Markov; their enthusiasm kept me busy enough to grow.

Legal Stuff.
============

Stdemo Player is shareware.

If you like Stdemo Player, a registration fee of $20 - $30 would
be appreciated. I think, it is a fair price. But if you think that
the price is too low or too high - send me whatever amount you
find appropriate.

When you register, I can replace irrelevant "MIK" icon on all
dialog boxes to another one (you may send your icon to me) and
will send the updated copy to you. Provided that your cash will
cover at least diskettes, time and postal expenses. If you support
my efforts, I can even customize Stdemo Player according to your
needs.

Please, send check or money order to:

Mikhail Kvitchko
289-D Crowells Road,
Highland Park, NJ 08904
USA


Comments? Questions? Suggestions?
I will be glad if you contact me at:

Internet:    [e-mail]
CompuServe:     Mik Kvitchko [71250,1660] (checked irregularly).

You may make copies of this program and give them to others as
long as all files are included and unaltered.


Disclaimer.
===========
I've taken great care to ensure the program performs as stated.
Still, I cannot guarantee this will be the case on every system.
As such, you agree NOT to hold me responsible for ANY damages
directly or indirectly related to the use of Stdemo Player. The
author of this software is not responsible for any damage due to
use of this program.  This software is provided without warrantee
of any kind.

A Personal Note...
==================

I write C better than English. Please excuse my mistakes and funny
constructions in the above text, if you noted some (I'm sure, you
did!). Especially articles... They are incomprehensible!

Thanks!